The Original Shareware 1.1/The Original Shareware (WeMake CDs)(Volume 1.1)(CDs, Inc)(1993).iso/16/pcfolded.zip/FOLDED.DOC

Text File | 1989-05-30 | 39KB | 724 lines

                FOLDED
               A folding editor
              (c) 1989
            By Todd Burkey

1.0 GENERAL:

  FOLDED is a dual mode editor that provides several advanced features
  not currently found in text and programming editors. FOLDED is primarily
  intended to be used as a source code editor. As such, it incorporates
  a folding feature similar to that found in thought processor programs
  but with added support for the C language (and eventually Pascal). FOLDED
  also has some relational capabilities. These allow the user to associate
  lines in their source files with sections of their documentation files
  and vice-versa. And both folding and relations are incorporated in such a
  fashion that they don't impact the original text files in any way.


2.0 FEATURES:

  FOLDED also has the standard set of editor features, with a few bells and
  whistles thrown in. It has dynamic 'as-you-type' searching, substitution by
  block/global/direction of a string or exact word match (i.e. change
  variable i to i_var throughout your code), block copy/move/kill in normal
  or rectangular region modes, marks that allow intra-buffer movement, easy
  movement between buffers, a trash can, variable skipping (point to a
  variable, press ^n to skip to the next occurrence of it, ^p for previous),
  configuration save (you can leave a multi-buffer edit session and come
  back to the exact place you left off with all buffer positions restored),
  built in help, prompting for the beginning user, one-key buffer cloning,
  and more.

3.0 LIMITATIONS:

  So what doesn't FOLDED do? Well, the first release will not have an UNDO
  feature. The trash can will have to do. It also is dual mode, something
  which may alienate some of the Emacs users out there (I am bi-editable,
  since I use Emacs on some systems, graphic shell editors on others, vi
  on still others). With a little work, the editor could actually be made
  to work either as a dual mode editor or a single mode editor (hint to
  hackers out there). It also could use some better screen optimization,
  since I tended to develop it on high speed displays. It is usable at
  2400 baud, but any slower than that and you are better off with ed.
  The first release also won't have any key binding capability. I still
  haven't decided upon the best approach to handle user-defined key maps.
  Finally, FOLDED isn't a layered editor. My goals during the development
  of FOLDED were to keep it relatively small (it is about 70K executable,
  <6000 lines of source) and fast, so layering as implemented in emacs-like
  editors was out.

4.0 HISTORY:

  I wrote FOLDED simply to learn.  Early on, I made a choice to 1) put
  basic 'must-have' functionality in the editor, 2) put advanced concepts
  into the editor that can't be handled by external programs (folding and
  relational features), 3) implement a simple to use and understand multi
  file editing capability so that moving between files and scratchpads
  was easy, 4) design the editor so that I could add enhanced 'wish-list'
  functionality as I determined I needed it, 5) ensure that the final
  version of the editor would function the same on my Atari ST at home as
  it does on the Sun or Apollo workstations and even as it does on the
  mainframes, and 6) keep the program small (I hate long loading times).
  The latter requirement somewhat dictates the earlier ones...at least
  for the first release.

  Having used many editors over the last 15 years, I decided to implement
  (or try to anyway) the features I liked most in the various editors. This
  decision steered me away from any thoughts of modifying an existing editor
  like emacs or vi, hence I diverged from the 'standard' a bit. First, FOLDED
  is an unconstrained editor. You can move your cursor anywhere on the screen
  and when you enter insert mode (or copy a rectangular block of text) FOLDED
  will take care of sticking in needed spaces. Another difference is that the
  editor does not 'wrap' lines. Instead, you can scroll/page the entire window
  sideways when necessary (the editor will do this for you if you are typing
  past the end of the right margin). I got too used to this feature on the
  Apollos, I guess. Also, FOLDED does not retain tab characters. Rather, they
  are replaced with white space on input and FOLDED will optionally 'optimize'
  your file when you write it out (i.e. inserting tabs wherever it can, removing
  trailing spaces on lines, etc). Actually, FOLDED doesn't even retain leading
  spaces in the way you might expect an editor to store them. All leading spaces
  in a line are compressed to an integer variable upon file read-in. The user
  still sees the spaces on the screen, but internally this sped up my folding
  logic (at the cost of almost going insane over the added code complexity...
  there is always a tradeoff).

5.0 COMPATIBILITY:

  The first release of FOLDED has been tested on BSD4.2/3 (Suns, Symetric,
  and Apollo), SYSVR3 (ETA-10...haha), the IBM PC, and the ATARI ST. It is
  being ported by others to the Mac. A preliminary port of the code to the
  BELLCORE MGR (window manager) environment took only two hours on a Sun
  workstation and provided individual windows for each buffer (with
  title bars).


6.0 EDITING COMMANDS:

  When you invoke FOLDED the first time, press the ? key to see a cheat sheet
  that tells you what each key does.  The following section covers the FOLDED
  commands in more detail. Note that whenever you are prompted for something
  in FOLDED, you will see the default response inside of brackets. Pressing
  the Return key will select this response. Also, in most cases, pressing
  the ESC key will return you to the top level command mode of FOLDED. It is
  important to remember that FOLDED is a DUAL mode editor. You start out in
  command mode and must use one of the insert commands to actually add text
  to the file you are editing. While in insert mode, you will continually be
  informed of this fact by a status line on the bottom of the screen.

6.1 REPETITION:
  Sometimes, you will wish to execute a command more than once. To do so,
  press the number keys to indicate the number of times you wish to do
  something and then do it. For example, if you wish to move down 4 pages,
  press 4J or if you wish to delete 8 characters, press 8d. Currently,
  only the movement and character delete commands utilize the feature.

6.2 MOVEMENT:
  The standard 'rogue' keys are used for single character cursor movement :-).
  Thus, the 'k' key will move you up one character, the 'j' key will move
  you down one character, the 'h' key moves you left one character, and the
  'l' key moves you right one character. As a natural extension of this, I
  chose to have the 'K', 'J', 'H', and 'L' keys move you farther in the same
  directions. For example, 'K' and 'J' will page you up and down, while the
  'H' and 'L' keys will move you 20 characters to the left or right.  If you
  are using an ATARI ST, then the arrow keys also function for cursor movement.

  You can also go to the beginning of a line by pressing the '^' key and
  go to the end of a line by pressing the '$' key. To go to a specific
  line number, just press the 'g' key and you will be prompted for the
  line number you wish to go to. For those of you who prefer the jump-page
  technique over scrolling, you can toggle between the two modes by pressing
  the 'p' key.

6.3 READING:
  FOLDED allows you to read files in a variety of ways. The standard way is to
  simply invoke FOLDED with a list of files to edit. When you are in FOLDED,
  you can read a file into a new buffer by using the ':r' keys. If you wish
  to view a file (i.e. not be able to edit it), then use the ':v' keys. And,
  if you wish to insert a file into the current buffer, then use the ':i' keys.
  In each case, you will be prompted for the file name you wish to read in.
  Another way of reading files is to simply position the cursor over a file
  name and press '^r' (Control-r). Likewise, you can press '^v' if you just
  want to view the file.

  Another way files are read in by FOLDED is 'on-demand'. This method is
  used by the relation commands to pull a file in if you request FOLDED to
  go to a related line and the necessary file isn't already read in. It is
  also used by the '-c' option when you invoke FOLDED to read all the files
  back in that you were editing when you last 'saved' a session. In both
  cases, FOLDED will place you at the correct position in the buffer.

6.4 WRITING:
  Writing files in FOLDED is a bit less complicated. To write out the current
  buffer, press the ':w' keys. If you happen to be in a 'blok'ed off region, you
  will be asked if you just want to save that region to a file. Then you are
  prompted for a file name. After entering the file name, you can optionally
  be prompted as to whether you wish to optimize the output text or not. If you
  choose to optimize, then tabs are inserted in the text wherever practical and
  tailing spaces on lines are stripped off. If not, then NO tabs will appear in
  the output text at all.

  Another way of saving files is to press the ':s' keys. This will 1) save a
  configurations file of which files you are currently editing (and where you
  are in each buffer), and 2) cycle through all edited files asking if you
  wish to save them.

6.5 INFO:
  A help cheat-sheet is available in FOLDED by pressing the '?' key from
  the top level command mode. If you aren't sure what is going on and '?'
  doesn't give you the help screen, then press the ESC key followed by the
  '?' key.

  If you want to know where you are in a file, or even which file you are
  currently editing, press the '=' key. You will see a highlighted line
  appear on the same line your cursor was on with the line and column number
  you are on relative to the file you are editing, the screen coordinates you
  are on, and the file name. Pressing the '=' key again will revert your line
  back to normal.

  One final type of information is available by pressing the 'X' key. This
  will display a full screen of info showing all the files you are currently
  editing, the number of lines, where you are in the file, part of the text
  in the line you are 'on' in the file, etc.

6.6 SEARCHES:
  Searching is an important part of using an editor from a programmers'
  viewpoint. It needs to be fast and consequentially involve as little typing
  as possible. To this end, I implemented two distinct types of searching in
  FOLDED. These are dynamic searching and word searching.

  Dynamic searching is similar to that used in many of the micro-emacs
  implementations. By pressing the '/' key in FOLDED, you will be prompted
  for what you wish to search for. As you type, FOLDED will search for what
  you are typing, moving you visibly to the line you are searching for and
  warning you when you have typed something that doesn't match. As you are
  searching in this fashion, the Backspace key will cycle you back to where
  the appropriate matches were found originally. Also the '^n' and '^p' keys
  will find the next or previous occurrences of the string you last found.
  The ESC key must be used to exit this mode of searching. Note that using
  the '/' key provides forward search capability and the '\' key provides
  backwards search capability. Also, when you press the '/' or '\' keys, you
  will see the last thing you searched for inside brackets. Pressing the
  return key when you see this will continue your search for the same text.
  This becomes very handy when you are searching multiple buffers for a
  string.

  Word searching is even easier. You just position you cursor over a word
  and press '^n' or '^p' to find the next or previous occurrence of the word.
  By default, the search is inclusive, so FOLDED will look for the next
  string that contains the word. If you press the '^e' key sequence before
  doing your searches, EXACTMODE searching will be enabled. This simply means
  that only exact word matches will be used during word searches. This turns
  out to be handy if you are checking to see where variable 'i' is used
  throughout a procedure. Pressing '^e' a second time turns off exact mode
  (it is a toggle).

  Note: Searching in FOLDED currently doesn't support any regular expression
  parsing. I thought I would miss this, since I find it mandatory in VI and
  EMACS, but so far I haven't needed it enough to bother sticking the code in
  (I did work out some of the logic to do the most common VI/EMACS REGEXP
  options).

6.7 BUFFERS:
  A number of commands allow movement between buffers. Direct selection of a
  new buffer is made using: 1) the space bar to cycle through the buffers
  one at a time, 2) the '^g' key sequence to allow you to go to a buffer
  directly (more on this later), 3) the 't' key to toggle back and forth
  between two buffers, and 4) the 'T' key to toggle back and forth between
  a buffer and the trash can. Whenever you go to a buffer using these methods,
  the screen will be repainted with the contents of the destination buffer
  and the name of the buffer will be displayed at the bottom of the screen.
  Using '^g' will allow you to cycle through the list of buffers at the bottom
  of the screen using the 'j' and 'k' keys to scroll and the Return key to
  select. If you forget how to do this, press the '?' key after pressing '^g'
  and you will get some help.

  Indirect selection of a buffer is made when you 'goto' a relation and FOLDED
  automatically moves you to a new buffer, or as mentioned earlier, when you
  read in a new file. Another way you can end up in a new buffer is by pressing
  the 'c' key. This will create an empty (scratch) buffer and place you in it.
  Pressing the 'C' key will make a complete copy (clone) of your current buffer
  into a new one and place you in it. Finally, using the '-k' key sequence will
  allow you to kill your current buffer (you will be prompted for verification
  before FOLDED does so), and then you will be moved to a previous buffer. Note
  that 'killing' the Trash Can simply empties it and leaves you sitting in the
  Trash Can buffer.

  Several comments are appropriate here about the Trash Can buffer. Every
  line you delete or multiple character sequence you delete will be moved
  to this buffer. Obviously, when you delete things from the trash can, they
  are really, truly gone. The Trash Can can be used as a scratch pad. In fact,
  the 'y' key will automatically insert the last line your cursor was
  positioned on in the trash can directly into your current line in another
  buffer. This is kind of like having an editable cut and paste buffer. Note
  that the Trash Can isn't automatically saved out by FOLDED, but it can
  be written out using ':w'.

6.8 BLOCKS:
  You can do things with regions of text in FOLDED using the 'blok' option
  key ('b'). Selecting this key will present you with the following prompt:

  blok-? (Start, End, Box, Norm, Move, Copy, Kill, Unset, Fold, Line <ESC>)

  Where the options are defined as follows:
      -Start  = current cursor position defines start of block
      -End    = current cursor position defines end of block
      -Box    = rectangular cut and paste region
      -Normal = normal cut/paste region
      -Move   = move block in buffer somewhere else
      -Copy   = copy block in buffer somewhere else
      -Kill   = move block to the trash can
      -Unset  = undefines a block
      -Fold   = fold a block
      -Line   = block the current line
      -ESC    = The escape key aborts the blok option command
  If you select the Move or Copy operations, FOLDED will further prompt you
  about where you wish to move the current buffers block to. The prompt you
  will see will be:

  To which buffer (c-current, t-tagged, s-select one) [ESC] ?

  Again, the ESC key will abort the blok option command. The 'c' key will
  simply copy the block into the same buffer at the cursor position. The
  't' key will copy the block into the buffer most recently tagged with the
  '^b' key (tag buffer key). Finally, the 's' key will put you into the
  same type of selector window that the '^g' key uses to select a buffer
  to go to.

  In all of these cases, when you are pushing a block of text to another
  buffer, the block will be inserted in the destination buffer immediately
  following the line that you were last on in that buffer (or in the line
  after the cursor if you are doing a box region copy/move). This method
  was implemented to ease the 'building' of code fragments from a number
  of other buffers (i.e. you are editing a file and realize you need a small
  code fragment from another file, so you press '^b' to mark you current
  buffer as the tagged buffer for copies, press ':r' and enter the other
  file name, find the text you want using the '/' key, use the 'bs' and 'be'
  keys to define the start and end of the block, press the 'bct' keys to do
  a block copy to the tagged buffer, and then press the 't' key to move back
  to where you were before you started.)

6.9 CHANGING:
  Two mechanisms exist for changing (substituting) text using FOLDED. First,
  the 's' key can be used to simply replace a single character. Just move the
  cursor over the character you wish to change, press the 's' key, FOLDED will
  prompt you for the new character, press it, and you are done. If you want to
  perform string or word substitutions, press the 'S' key. FOLDED will prompt
  you for the text string you wish to search for (the word under the cursor
  is your default response), and then prompt you with what you wish the word
  to be changed to. Then FOLDED prompts you for the nature of the search and
  replace logic to use. Your choices are:

  Option (A-all, U-up, D-down, E-exact, <ESC>) [once]:

  If you select 'A', then all occurrences of the string are searched for and
  the substitution is made. If you press 'U' then replacements are made
  from the current position and on up in the buffer. If you press 'D', then
  the replacements work downward in the buffer. If you press the 'E' key,
  the replacements are by exact word match only. Finally, if you just press
  the return key, then only the first match is changed (i.e. this is a quick
  'change word' command).

  Note that if you define a 'blok'ed region of text and happen to have your
  cursor inside that region when you do a substitution, you will be prompted
  as to whether you want your substitutions restricted just to that region
  of text. Also, keep in mind that folded away text is NOT affected by a
  global substitute. If you need to do a global substitute that looks inside
  folds, press the '^f' (unfoldall) key first.

6.10 DELETING:
  To delete the character under the cursor, simply press the 'd' key. To delete
  the whole line you are on, press the 'D' key. If you wish to do global
  deletes of lines that contain or don't contain a particular string or word,
  press the '-d' or '-v' key sequences. The '-d' key sequence will delete
  every line that matches your search criteria, while the '-v' sequence deletes
  every line that does not contain it. Both sequences will prompt you for the
  string and ask if you wish the string to be inclusive or an exact word
  match.

6.11 INSERTS:
  Inserting text into a buffer is quite simple. Simply move your cursor to
  where you wish to start inserting and press the 'i' key to start inserting
  before the cursor. When you are done typing in text and wish to move to
  another part of the file or use any of the editor commands, just press the
  ESC key. Note that while you are insert mode, you will see the following
  prompt in bold at the bottom of the screen:

    Insert mode (^p-toggle auto indent). <ESC> when done.

  so it is pretty hard to forget how to get out of insert mode. The '^p' key
  sequence may be used to turn off the auto-indent mode. Currently, auto-indent
  is always turned on by default (this will be handled via a configuration file
  in future versions.

  Three other commands are available for inserting text. The 'a' key is just
  like the 'i' key, except it starts inserting text after the current character
  under the cursor.  The 'I' key will insert a line in front of the current
  line, tab over so that the new line is indented to the same level as the
  previous line, and then puts you into insert mode at that positions. The
  'A' key does the same thing, but creates the line after the line that your
  cursor is on.

6.12 FOLDING:
  Folding is a complex enough topic that it is further described in Appendix 1.
  The following is simply a list of the current set of commands that involve
  folding:
     f-fold by indentation,
     F-fold by logic,
     bf-fold a defined block
     ^f-toggle unfoldall,
  NOTE: press f or F on a fold to unfold it

6.13 RELATES:
  Relations are also a complex topic. For further information, see Appendix 2.
  The current set of commands are defined as follows:
    Rsl-Relate Set Line
    Rsw-Relate Set Word
    Rgl-Relate Goto Line
    Rgw-Relate Goto Word
    Rkl-Relate Kill Line
    Rkw-Relate Kill Word
    Rp-Relate Pop

6.14 MARKING:
   Marks are a handy feature to get used to, since they let you move around
   within and between buffers in a very efficient manner. FOLDED utilizes
   a one character global mark concept. All mark commands are invoked by
   first pressing the 'm' key. The user then sees the following prompt:

   mark-? (Set, Goto, Kill, Clear all, <ESC>)

   Answering 's' will prompt the user for a keypress and assign the current
   location (line number, character position, buffer number, etc) to that
   key. For example, typing 'msa' will assign the current location to the
   'a' key. Answering 'g' will prompt the user for which tag to go to. For
   example, to get to the location tagged with the 'a' key, you simply type
   'mga' and you will be immediately moved to that location. Note that FOLDED
   searches in the current buffer for the 'tag key' first and then scans
   all buffers. If you answer the prompt with a 'k' FOLDED asks whether you
   wish to kill the tag(s) associated with the current line or a specific
   key (you either press the key or press return to select the current line).
   So pressing 'mka' will remove the tag associated with the 'a' key. Finally,
   select the 'c' option if you wish to remove all tags defined in the current
   buffer.

6.15 EXTRAS:
  One of the most important commands you will need to remember is the 'Q' key.
  Pressing this key will exit you from FOLDED. If you have any buffers that
  have been modified, but haven't been written to a file yet, FOLDED will ask
  you if you are sure you wish to exit. Note that on most systems, pressing
  CTRL-C will accomplish the same effect as pressing 'Q', although the effect
  will be immediate if the compiler/OS used doesn't support signals (CTRL-C
  is normally trapped to vector you to the same routine that pressing 'Q'
  does). Also, on BSD systems, pressing CTRL-Z will cleanly interrupt your
  editing session and allow you to resume at a later time (via fg).

  If you wish to invoke a shell or run an external program from within FOLDED,
  simply press the '!' key and either press return when prompted, to start up
  a shell, or type in the command you wish to run.

  To execute an external macro on the currently 'blok'ed region of text,
  press the 'x' key. Right now, this command is experimental and really should
  be considered unimplemented. I am still toying with different ideas in the
  definition and implementation of external macros. Note that having external
  macros does not preclude having internal macros at some future date.

6.16 KEY TRAINING:
  Occasionally, you will realize that you have to do something really
  fairly simple a number of times. The use of the 'trained key' concept in
  FOLDED comes in useful here. To turn on key training, press the '[' key.
  You will be informed that key training is now turned on and that you can
  turn it off with the ']' key. Now do whatever sequence of commands you
  need to do and press the ']' key. You will be informed that the 'e' key
  has now been trained. Now, every time you press the 'e' key you will see
  the exact same sequence of commands performed.

  Note: the training does not carry over between edit sessions, but it will
  carry over as you switch between buffers (in fact, switching between buffers
  may be part of what the key is supposed to do). Also keep in mind that
  this can be a fairly dangerous command, so keep the complexity of what your
  are trying to do down until you are comfortable with the feature.


7.0 BACKUP PROTECTION:

  If FOLDED detects a local directory called febackup, then backup copies of
  anything you edit will be placed in that directory. A rename operation is
  performed on the original file, so this means that only local partition files
  will be backed up in this fashion. Backups only take place at the time you
  save a file the first time during an edit session, so no unnecessary backups
  are made.


8.0 FOLDED CONTROL FILES:

  If folded detects a local directory called foldinfo, then FOLDED will store
  all its control files there rather than clutter your directory with them. A
  control file is created only when the file being edited is saved and has some
  folding or relations in it. The control file will be a file of the same name,
  but with an 'f' inserted immediately after the final '.' in the name...so
  'test.c' has a control file called 'test.fc' and 'junk' would have 'junk.f'.


9.0 ENVIRONMENT VARIABLES:

  Several Environment variables may be used if you wish to avoid some prompting
  by FOLDED. They are:

    FE_ASCII   - Save control files in ASCII (easier to mail that way)
    FE_BINARY  - Save control files in BINARY (a bit faster and more efficient).
    FE_NOTABS  - Always write files without tabs (useful on the Apollos).
    FE_TABS    - Always fully optimize the files when writing.
    MGR_FONT   - Size of the font used under MGR for the windows.


10.0 Coding Style

  I expect to take some flak on my coding style. I wrote most of this editor
  in evenings after LONG days of mostly Pascal code design at ETA, so I tended
  to keep things fairly simple, brute forcing the code where necessary. Most of
  the current code I wrote as throwaway test code and just haven't had time to
  re-design the logic. I also didn't originally plan on releasing the sources
  to this code, so it is set up in such a manner that I can go back to it a
  year or two from now and immediately be able to pick up where I left off.
  Unfortunately, this doesn't mean there is sufficient in-line documentation
  for others to port by.

  After (if) I get gcc ported to my Symmetrics (or if I get a job working for
  a company that has a good ANSI compliant C compiler), I'll try to get FOLDED
  'up to' ANSI C standards.  I hopefully have put in sufficient IFDEF's to
  help minimize the porting issues, but feel free to send in any extra ones
  you find your type of system needs.


11.0 Obtaining Updates to FOLDED

  FOLDED is an evolving product. As such, I expect to make fairly frequent
  updates and release new versions several times a year (probably more often
  in the first year or so). If you have USENET access, then keep an eye on
  the sources newsgroups for diffs and/or new versions. If you want the
  next major release earlier than it trickles out to the net (i.e. a month
  or so earlier than normal), then follow the procedure outlined below but
  remember to specify which release you currently have. Of course, this
  would require that you have access to a PC or ST (or a floppy drive on
  your Unix system and the mdrive PD software).

  For those of you who received a binary only version of FOLDED (the PC
  or Atari ST versions), the most recent version with sources can be obtained
  by sending $20 to the address shown below. Please specify computer and media
  type. I can create SSDD or DSDD 3.5" disks for the Atari ST and 360K 5.25"
  disks or 720K 3.5" disks for the IBM PC. If you are outside the United
  States, then please add $5.00 shipping and handling (I prefer to ship by
  Air Mail). Ordering in this way will register you for a mailing notice of
  the next subsequent 'major' update.

    Todd Burkey
    3546 Pilgrim Lane
    Plymouth, MN 55441

    Home Phone (eve/wkends): [phone]
    BBS I can be reached at: [phone]
    Usenet Address via UUCP: pwcs!stag!trb

12.0 COPYRIGHT INFORMATION

  The following paragraph defines the basic copyright information for
  FOLDED. It is included at the top of each of the source modules and
  must NOT be changed or removed from this document without written
  permission of the author.

  This file is part of the FOLDED sources. FOLDED is a folding editor and
  is copyrighted 1989 by Todd Burkey, 3546 Pilgrim Lane, Plymouth, MN 55441.
  The author gives you the right to further distribute FOLDED, as long as
  1) this notice remains intact in the sources, 2) the sources are made
  available to the end user, and 3) the editor isn't sold for a profit. The
  author makes no representations or warranties of fitness of this program
  for any purpose. As with any free program, you use it at your own risk.

Appendix 1: FOLDING

  Obviously, a fundamental concept in using FOLDED is that of folding.
  Folding in a text editor is a mechanism that allows you to cause
  sections of code or text be replaced by a single line of text. This
  is useful for 'hiding' away clean and functional sections of code
  while you work on and only see the parts that you are currently
  debugging. It also proves useful for tucking away big comment blocks.

  Worried that folding will change your source code? Don't worry, the
  act of folding doesn't affect the edited file at all...even when saved.
  When you save a file that has folds in it, a separate control file
  is also saved under your current directory. See the section in the
  documentation titled 'CONTROL FILES' for more info on this.

  In FOLDED, I implemented three types of folding. In each case, a
  segment of your file is reduced such that all you see is the first
  line of the segment in reverse image (or bold, depending on your
  standout terminal mode). First, is the simple 'fold a marked block'.
  This allows you to mark any arbitrary region of text and fold it away.
  For example, lets say we had started with the following text (the
  numbers are just for reference in this documentation):

   1: main()
   2: /* GID for main - Just a test case
   3:     Author: Todd Burkey
   4:     Date:     1/27/89
   5:     DESC:     Methodology for a test case
   6: */
   7: {
   8:    if(this==that) {
   9:      do_something_that_works();
  10:      }
  11:    }

  By defining a region between lines 2 and 6 and then folding, what you
  would see on the screen would be:

   1: main()
   2: /* GID for main - Just a test case    <-pretend this line is bold
   7: {
   8:    if(this==that) {
   9:      do_something_that_works();
  10:      }
  11:    }

  Another method of folding is that based on 'indent level'. The logic
  behind indent level folding is simply to start with the line the user
  is currently on, move down in the text until an indent occurs, and
  then continue down until an undent occurs that is less than or equal
  to the original lines 'indented' position. For example, if you
  had been on line 8 in the above 'folded' text when the 'f' key was
  pressed, you would see the following:

   1: main()
   2: /* GID for main - Just a test case    <-pretend this line is bold
   7: {
   8:    if(this==that) {            <-pretend this line is bold
  11:    }

  Unfortunately, most source code contains lots of things that tend to
  break up the clean indentation levels, so I added a third folding
  mechanism. This one is a little smarter in that it does a 'logical
  fold'. A logical fold looks for logical block begin/end marks in the
  code (the braces in C) and skips around comments, strings, etc. For
  example, if you had pressed the 'F' key on line 1 in any of the above
  steps, you would end up with:

    1: main()                <-pretend this line is bold

  In all cases, unfolding the text is performed by simply moving to the
  folded line and pressing the 'f' or 'F' key.

  Folding isn't all that novel a concept. It has been used for years now
  in thought processor programs on the Mac, IBM PC, and even back in the
  CP/M days. Thought processors usually use the 'fold by indent level'
  technique. Take the following simple example:

  FOLDED Information
    * specifications    <-pretend this line is bold
    * plans        <-pretend this line is bold
    * problems        <-pretend this line is bold

  This is all I see when I use FOLDED to call up my folded.info file.
  Now, if I move to line 3 and press the f key, I will see:

  FOLDED Information
    * specifications    <-pretend this line is bold
    * plans
      - Documentation    <-pretend this line is bold
      - Enhancements    <-pretend this line is bold
      - Bullet-proofing <-pretend this line is bold
    * problems        <-pretend this line is bold

  In summary, folding is fully hierarchical (i.e. a fold can contain any number
  of folds), it is smart (it can fold based on programming logic blocks and
  indentation level), and it is retained from one edit session to the next.
  The actual commands (and their associated key bindings) that involve folding
  are:

    indent fold (f) : fold based on indent level logic
    smart  fold (F) : fold based on {} logic
    unfold (f or F) : unfold the fold under the cursor
    temp unfold (^f): temporarily unfold all folds (for searching/sub'ing)
    re-fold all (^f): yep, CTRL-f is just a toggle
    block fold    (bf): fold current block region


Appendix 2: RELATING

  The word 'relations' in the field of databases conjures up images of opening
  up a large database, finding a particular entry, moving to a particular
  field, and, with several keystrokes, calling up not only another database,
  but a specific record in that database. Now, I have never understood why
  we couldn't have similar capabilities in a text editor. We can envision
  having a document file, moving to a specific part of the document, calling
  up the source code file related to that part of the document, and then
  moving to the appropriate spot in the source file. We can even imagine
  moving through the source code and finding a structure (or variable) and
  wishing we could immediately view the definition of the structure. These
  scenarios are fundamentally the same as those handled by a relational
  database program.

  Relationships as pertains to editors (and, of course, in this context, FOLDED)
  primarily involve two concepts.  First, there are word relationships.  These
  are something like 'glossary' entries in that you define a word once in a file
  and then can immediately go to the exact place you defined it from anywhere in
  the file (or any other file you are currently editing.) From a programming
  viewpoint, this simply means that you can move your cursor over a structure
  name in a source file and with a few keystrokes be placed immediately in an
  include file at the place the structure is defined.  A second relationship type
  is that of line relations.  These are basically invisible links that relate a
  line in one buffer to a line in another buffer.  This type of relationship
  allows you to easily move back and forth between source code and program
  outlines/documents.  Folded will even open up a file if you try to go to a
  relation in a file that you aren't currently editing.

  FOLDED supports a number of commands that allow easy creation and use of
  these relationships. The following key sequences are used to perform the
  most common relation operations:

   Rsl (Relate Set Line): The current line becomes 1/2 of a line relationship.
              The next Rs command will complete the relationship.
   Rsw (Relate Set Word): The current word is indexed for reference.
   Rgl (Relate Goto Line):FOLDED looks at the first line with a relation on or
              above the current line and goes to its related line.
              If the related line is in a file not currently being
              edited it will be opened for viewing.
   Rgw (Relate Goto Word):Read the word under the cursor and move to the correct
              file that it was defined in.
   Rkl (Relate Kill Line):Kill the relationship for the current line.
   Rkw (Relate Kill Word):Kill the relationship for the current word.
   Rp  (Relate Pop):      Pop back to where you were before the last Relate Goto.
              The pop stack is currently 10 levels deep.

  As with folding, the relationship information does not affect the actual
  files you are editing. In fact, the information is simply saved out as part
  of the folding info files. It is also important to note that neither folding
  or relations affect the speed of loading, saving, or using the various editor
  features to a notable extent.

  Since I added relations very late in the development of the editor, I have a
  feeling that this area will see the most improvement over the next year. I've
  already decided that I need a few more commands to do things like 'move'
  and 'view' relationships.

Appendix 3: IMPLEMENTATION DETAILS

  Folded uses a doubly linked list to store lines internally. It mallocs
  the exact amount of memory a line needs on read-in, but as you modify lines
  it will malloc additional memory in 4 byte chunks...so you can end up with
  some wastage if you edit a lot of lines in a file. FOLDED keeps track of a
  lot of information about lines in the buffers, so there is quite a bit of
  overhead in using FOLDED. I place it pretty close to emacs in the amount
  of overhead required for 'data' storage, but since the executable is only
  about 60K it wipes emacs away in raw loading time (program+files). I haven't
  had time to optimize the code for speed yet, but things like searching and
  substituting are significantly faster than emacs and slightly faster than
  vi. This is partly due to the design of the editor and also may be due to
  FOLDED's lack of regular expression parsing routines.

  The first version of FOLDED isn't as optimized as it could be in the sense
  that ints may be used where chars may get by. Also, there may be tricks I
  don't know about that could compress the amount of overhead I incur in the
  storage of lines, buffers, etc.